home *** CD-ROM | disk | FTP | other *** search
/ Aminet 5 / Aminet 5 - March 1995.iso / Aminet / dev / m2 / Turbo_1.lha / modula / docs / TURBO.DOC < prev    next >
Text File  |  1995-01-24  |  17KB  |  438 lines
  1. ================================================================================
  2.  
  3.                             Turbo Modula-2 V1.40 (26/Jan/95)
  4.  
  5.     Turbo Modula-2 (c) Copyright 1994/1995 by Amritpal Mann, All Rights Reserved
  6.  
  7.                 Email: turbo@econet.demon.co.uk
  8.  
  9. ================================================================================
  10.  
  11.     This is a freely distributable Modula-2 development system.
  12.     The version of Modula supported is as described in Niklaus Wirth's book:
  13.     Programming in Modula-2, 4th edition (Springer-Verlag)
  14.  
  15.     Turbo Modula-2 consists of:
  16.  
  17.         A compiler(M2C), a link utility(M2L), an error lister(M2E),
  18.         and a program builder(M2B).
  19.         Interface modules for V40 of the AmigaOS & corresponding linker library,
  20.         ANSI C standard library definitions as well as those from PIM.
  21.  
  22.     A source level debugger(M2D) is under development.
  23.  
  24.     The compiler reads source code in a single pass which means fast
  25.     compilation. Internally however it performs several passes over each
  26.     procedures statement sequence in order to generate fast and compact code.
  27.     Typically, generated code is 25% smaller & 75% faster than the
  28.     commercial Amiga Modula-2 compiler used for the initial bootstraps.
  29.  
  30.     Turbo does not have its own linker, instead it requires a 'C' compiler
  31.     front-end to link generated code.
  32.     The unregistered freeware version of Matt Dillon's excellent C system,
  33.     DICE, has been included and contains 2 necessary programs, DCC & DLINK,
  34.     as well as vital startup code(c.o) and support libraries(c.lib,auto.lib,x.o)
  35.     Note that Turbo does NOT produce 'C' as intermediate output, it just uses
  36.     DCC & DLINK to link and add startup code the machine code it generates.
  37.  
  38.     You do not need to know how to use DICE in order to generate M2 executables,
  39.     M2L calls DCC for you, all you need do is extract DICE (see below).
  40.     The reason for using DICE instead of say BLINK, are that DICE has excellent
  41.     support for generating residentable programs, also the standard C library
  42.     supplied with DICE becomes automatically available and finally
  43.     (for those of us who have slow(er) amigas) DLINK runs fast!
  44.  
  45.     The unregistered freeware version of DICE may only be distributed complete &
  46.     unmodified. This also applies to Turbo Modula-2.
  47.  
  48.     The minimum required setup in order to use Turbo is 1MB of memory, 1.3
  49.     workbench and 2 disk drives. However I recommend that you should have at
  50.     least 1MB of available(free) memory and a hard disk.
  51.     When runnning under OS 1.3 make sure NEWCLI, ENDCLI and RUN are in youre
  52.     path, even better make them resident.
  53.     To use M2B you really need a real-time clock or otherwise set the time at
  54.     bootup or instead use M2C & M2L directly.
  55.     If you dont have a RTC you can use a software hack: examples/src/IncTime.mod
  56.  
  57. DICE Extraction
  58. ===============
  59.  
  60.     The file dice/dice.lha contains the DICE system.In order to save your
  61.     hard disk space, the dice/M2EXTRACT script will extract the files that we
  62.     are interested in:
  63.  
  64.         >cd dice
  65.         >execute M2EXTRACT
  66.  
  67.     You can of course extract the entire archive if you prefer.
  68.     If you already have DICE installed on your system, and are therefore not
  69.     extracting it again, you should delete the appropriate lines in the
  70.     s/startup script.
  71.  
  72. Installation
  73. ============
  74.  
  75.     Add the following lines to your s:user-startup (startup-sequence under 1.3):
  76.  
  77.     >assign  MODULA: <dir> ; <dir> = directory where you unarchived Turbo
  78.     >execute MODULA:s/startup
  79.  
  80. Assignments
  81. ===========
  82.  
  83.     MODULA: is expected to be assigned to the root directory of the unarchived
  84.             system.
  85.  
  86.     MLIB:   should be assigned to MODULA:mlib
  87.  
  88.     s/startup will make the above ASSIGNs for you.
  89.  
  90. Directory Organisation
  91. ======================
  92.  
  93.     docs/
  94.  
  95.     M2OPTS      Default M2OPTS file (see below).
  96.  
  97.     examples/   Some example programs
  98.  
  99.     amiga/    20000 lines of definition modules for V40 of the AmigaOS,
  100.             these files were hand translated from Commodores header files.
  101.  
  102.     ansi-c/     Definition for the Ansi-C library that comes with DICE.
  103.  
  104.     m2lib    Definitions for some of the functions in M2.lib.
  105.             Also contains source for m2_main.o.
  106.  
  107.     m2/        Definition for some library modules.
  108.  
  109.     sym/        Symbol files for above definition modules.
  110.  
  111.     obj/        Compiled object modules, for the implementation modules in
  112.         above directories
  113.  
  114.     mlib/       Contains Modula-2 support code (m2.lib & m2_main.o).
  115.             MLIB: is assigned to this.
  116.  
  117.     bin/        Residentable executables for M2B, M2C, M2E, M2F, M2L & M2S.
  118.                 All these programs were developed completely from scracth by
  119.                 the author, the initial M2C bootstrap was done using
  120.                 M2Amiga V3.32.
  121.                 These programs are only runable from the cli/shell.
  122.  
  123.     dice/       DICE system. If you want to redistribute DICE then you must
  124.         include all the files in the dice.lha archive.
  125.  
  126.     s/        Contains startup and object file caching scripts.
  127.  
  128. Filename extensions
  129. ===================
  130.  
  131.     *.err    Binary error file generated by M2C & M2B, used by M2E.
  132.     *.mod    Program/implementation module (ascii text).
  133.     *.def    Definition module (ascii text).
  134.     *.o      Standard Amiga object file, generated by M2C from a *.mod file.
  135.     *.sym    Symbol file generated by M2C from a *.def file.
  136.     *.lib    Linker Library. A concatenation of *.o files.
  137.     *.lnk    Linker object file list(ascii), written to the T: directory by M2L,
  138.              read by DCC.
  139.     *.cmp    Compiler input file list(ascii), written to the T: directory by
  140.          M2B, read by M2C.
  141.  
  142. Error Lister (M2E)
  143. ==================
  144.  
  145.     If M2B or M2C encounter errors while processing a source file, then a
  146.     binary error file will be generated.
  147.     Use M2E to view the errors encoded in this file.
  148.  
  149.     usage: m2e modulename
  150.  
  151.     On finding errors, M2B and M2C will automatically invoke M2E.
  152.  
  153. Program Builder (M2B)
  154. =====================
  155.  
  156.     M2B will take care of compilation and linking for you.It checks file
  157.     timestamps to see which files need to be (re)compiled/(re)linked.
  158.  
  159.     M2B is like MAKE, but instead of using a makefile it scans import lists.
  160.  
  161.     usage: m2b [-f][-z][-t] [compile/link options] filename [DCC options & args]
  162.  
  163.     -f: Force all time comparisons to fail(all modules will be (re)compiled).
  164.  
  165.     -z: Write out the name of each file as it is read.
  166.  
  167.     -t: Don't actually call M2C & M2L just print the commands that would have
  168.         been executed.
  169.  
  170.     example:
  171.  
  172.                                 /-------- -s passed to DCC
  173.       >m2b -t -p -b -q foo.mod -s
  174.                ^--^--^------------------ -p -b -q are compiler(M2C) options
  175.                                          -q is also an M2L option.
  176.  
  177.     Assuming that foo.o is older than foo.mod and foo.mod does not import
  178.     any other module then M2B will call M2C & M2L as
  179.  
  180.       m2c -p -b -q foo.mod
  181.       m2l -q foo.o -s  (but only if m2c did not fail)
  182.  
  183.     M2B is quite happy to accept definition & implementation modules as
  184.     primary input.
  185.  
  186.     You may find the TOUCH program (in dice/bin/) useful when using M2B.
  187.  
  188.  
  189. Compiler (M2C)
  190. ==============
  191.  
  192.     usage: m2c [-D][-C][-b][-p][-r][-s][-v][-w][-q][-l] {-Mdir} {[@]filename}
  193.  
  194.     filename:
  195.         File to be compiled
  196.         If a filename does not end in .mod or .def, then it is assumed to be
  197.         a .mod and so .mod wiil be appended.
  198.  
  199.     @filename:
  200.         Filename is an ascii text file that contains a list of filenames to be
  201.         compiled (this list is normally created and passed to M2C by M2B).
  202.  
  203.     -020:
  204.     Generate MC68020+ machine code.
  205.     Dont use this option unless your Amiga has a 68020/30/40/60 processor.
  206.     A1200/A3000/A4000 computers all come installed which one to these chips.
  207.     At the present all this option will do is replace the 32bit__divs/__muls
  208.     subroutine calls with inline 020+ DIV.L/MUL.L instructions.
  209.     If you wish your code to assert overflow errors during 32bit multiply
  210.     expressions then you will need to enable this option (and also -v)
  211.  
  212.     -D: Use large data model (default is small data model).
  213.         If your program declares more than 64K of global variables then you must
  214.         enable this option for each constituent module (except library
  215.         modules that were compiled small data & -l), otherwise linking will
  216.         fail.
  217.  
  218.         Try to avoid using this option.
  219.         By allocating large data structures on the heap you can easily avoid
  220.         the need to use it.
  221.  
  222.         When compiling small data you are resricted to declaring 32K of global
  223.         variables per module.This is not strictly true, you can declare up to
  224.         64K per module but you must not make any compile time references to
  225.         any variable outside the first 32K.
  226.  
  227.         When using small-data the total global variable space per linked
  228.         program must not exceed 64K.
  229.  
  230.         No such restrictions exist if you enable -D.
  231.  
  232.         Using the small data & code models will make your program more compact.
  233.         Compiling all modules small data will also allow a program to be
  234.         made fully resident (DCC & DLINK option -r).
  235.  
  236.     -C: Use large code model (default is small).
  237.         If a module compiles to about 32000 bytes or more, then you may need to
  238.         enable this option (depending on whether linking fails).
  239.         If a module compiles to more than 32767 bytes then you definitely need
  240.         to enable this option.
  241.         The maximum code size using large code is 48K (per module).
  242.  
  243.     -b: Enable array bounds checking.
  244.     -r: Enable range checking, when converting between subrange types.
  245.  
  246.     -v: Enable overflow/underflow checking.
  247.         Overflow checks are inserted by the compiler when it encounters
  248.         '+','-','*' & ABS() expressions and also after INC/DEC statements.
  249.         Unless you enable -020, overflow checks will be not performed on 32bit
  250.         multiplys (8 & 16Bit ones will be detected on all processors).
  251.  
  252.     -z: Enable zero divide/modulus checking.
  253.         Zero checks are not performed on floating point divides.
  254.  
  255.     -s: Enable automatic stack checking.
  256.         Any coroutine or task code should not use stack checking.
  257.         The checking routines demand that 2K of stack be always available.
  258.     Its also possible to insert stack checking code manually (see M2Lib.def)
  259.  
  260.     -p: Enable pointer checking.
  261.         The compiler will insert code to check that all pointer accesses are
  262.         within a specific range. At the moment the bounds are fixed to 1K..16M.
  263.         If you're Amiga has valid memory outside this range (and you're program
  264.         might access it) then you cannot use this option (try -P instead).
  265.  
  266.     This range checking is also done on procedure variables.
  267.  
  268.         Programmers with Amigas that do not have MMUs (and so can't run the
  269.         enforcer program) will find this option very useful.
  270.         For best results, use pointer checking in conjunction with Commodores
  271.         MUNGWALL program (but -p can still trap a lot of bugs without it).
  272.  
  273.         Pointer checking should only be used during program development.
  274.         DO NOT DISTRIBUTE PROGRAMS THAT CONTAIN ANY -p/-P GENERATED CHECKING
  275.         CODE.
  276.  
  277.     -P: like -p except upper bound = 2Gb.
  278.         Try this if -p wont work on your system.
  279.  
  280.     -w: Disable compiler warning reports.
  281.  
  282.     -q: Shut the f*ck up.
  283.  
  284.     -l: (equivalent to the DICE option -S)
  285.         Name BSS(global variable space) section libbss instead of just 'bss'.
  286.         Use this option to compile re-usable modules that do not have much BSS.
  287.         This will enable you to use small code library modules with (large code)
  288.         program modules that declare a lot of BSS.This option avoids the need to
  289.         have two different versions (one small & one large data) of said
  290.         modules.
  291.         Dont use this option unless you know what you are doing.
  292.  
  293.     -M: Add dir to the symbol file directory search path.
  294.         If a dir/sym/ subdirectory exists, it will be added instead.
  295.  
  296.     It is possible to set/clear some of these options inside a source text
  297.     by using comments, see extensions.doc.
  298.  
  299.     If a Modula-2 run-time error occurs (illegal case index, halt called,
  300.     array/pointer checking etc) the run time support code (in M2.lib) will
  301.     display a requester with the name of the module and line number of where the
  302.     error occurred.
  303.  
  304.     ¥ou can use DICE DOBJ to view the machine code generated by the compiler.
  305.  
  306.  
  307.   One pass compilation
  308.   --------------------
  309.  
  310.     The compiler operates in a single pass, this means that you must declare
  311.     variables & procedures before you use them.The compiler provides the FORWARD
  312.     keyword in order to allow early declarations for procedures that are
  313.     implemented later.
  314.  
  315.     PROCEDURE f( ) ; FORWARD ; (* implementation must be in the same scope *)
  316.  
  317.     PROCEDURE g( ) ;
  318.     BEGIN f( ) ;
  319.     END g ;
  320.  
  321.     PROCEDURE f( ) ; (* alternatively we could nest f( ) inside g( ) *)
  322.     BEGIN g( )
  323.     END f ;
  324.  
  325.     If a procedure is declared in a definition module then a forward declaration
  326.     in the corresponding implementation module is never required.
  327.  
  328.   Type sizes & extremal values
  329.   ----------------------------
  330.  
  331.             size (bytes)                range
  332.             ============                =====
  333.  
  334.     SHORTCARD   1                     0 .. 255
  335.     CARDINAL    2                    0  .. 65535
  336.  
  337.     SHORTINT    1                   -128 .. 127
  338.     INTEGER     2                 -32768 .. 32767
  339.     LONGINT     4                -(2^31) .. (2^31)-1
  340.  
  341.     SHORTREAL   4                   Motorola FFP
  342.     REAL        4               IEEE single precision
  343.     LONGREAL    8               IEEE double precision
  344.  
  345.     There is also a LONGCARD datatype which is declared as a
  346.     LONGINT[0..MAX(LONGINT)].
  347.  
  348.  
  349.   Compiler Restrictions
  350.   ---------------------
  351.  
  352.     As already mentioned the compiler can only generate object files up to
  353.     48K (any bigger than 32000 (I DO NOT mean 32767!) bytes should be compiled
  354.     large code, linking will fail if you do not).
  355.  
  356.     Sets sizes are restricted to 32 bits.
  357.     Structured types (arrays and record) can NOT be returned from functions.
  358.     At somestage I may remove the above 2 restrictions.
  359.  
  360.     Module names must be less than 30 characters (AmigaDos restriction)
  361.     All other identifiers and string literals must be less than 200 chars long.
  362.  
  363. Symbol file Cache (M2S & M2F)
  364. =============================
  365.  
  366.     The compiler automatically caches symbol files.
  367.     If youre system does not have much memory, then you will need to flush
  368.     the cache on a regular basis, or 'setenv M2SYMCACHE=OFF'.
  369.  
  370.     To list the cached symbol files use M2S.
  371.     To flush the symbol cache use M2F.
  372.  
  373. Linker frontend (M2L)
  374. =====================
  375.  
  376.     M2L calls DCC (which in turn calls DLINK) to link the object modules
  377.     generated by the compiler into an executable file. M2L is itself normally
  378.     called by M2B (M2B->M2L->DCC->DLINK).
  379.  
  380.     Usage: m2l [-q] {-Mdir} module[.o] [DCC options & args]
  381.  
  382.     -q    : Quiet, don't print the path of each file as it is read.
  383.  
  384.     -Mdir : Add directory dir to the object file search path.
  385.             If a dir/obj/ subdirectory exists, it will be added instead.
  386.  
  387.     module: Program (root) module name.
  388.             This object module must be in a local directory
  389.  
  390.     Anything on the command line that follows the module name is passed to DCC.
  391.  
  392.     example: m2l -q foo -s -r
  393.                          ^--^-- passed to dcc.
  394.  
  395.     This will invoke DCC:
  396.  
  397.     dcc -Lmlib: @t:foo.lnk -s -r -ofoo
  398.  
  399.     Where t:foo.lnk (intermediate file generated by M2L) will contain:
  400.  
  401.     m2_main.o
  402.     foo.o
  403.     m2.lib
  404.     ------
  405.  
  406.     m2_main.o m2.lib are normally in directory mlib: (modula:mlib)
  407.  
  408.     See DICE/DOC/DLINK.DOC for further information on linking.(You may
  409.     have to extract this file)
  410.  
  411.  
  412. M2OPTS
  413. ======
  414.  
  415.     An optional ascii text file named M2OPTS in the MODULA: directory can
  416.     specify M2C and M2L command line options.
  417.  
  418.     M2L filters M2OPTS looking for -q & -M's ignoring all other options.
  419.     Options in M2OPTS are scanned before command line options.
  420.  
  421.     An M2OPTS text in the current directory will override the one in MODULA:.
  422.  
  423. Debugging
  424. =========
  425.  
  426.     Ideally Turbo should include a source level debugger.
  427.     The DCC options '-s' dumps symbols into final executable so you can
  428.     atleast use a low level debugger (eg Devpac Monam), this does however
  429.     require knowledge of M68000 assembler.
  430.  
  431. Contacting the author
  432. =====================
  433.  
  434.     Please report any bugs/comments or suggestions to turbo@econet.demon.co.uk
  435.     or subscribe to the mailing list.
  436.     I reply to all the mail that i am sent.
  437.  
  438.